Skip to content

Converge what to build before design starts - #154

Merged
shinpr merged 4 commits into
mainfrom
feat/requirement-convergence
Jul 31, 2026
Merged

Converge what to build before design starts#154
shinpr merged 4 commits into
mainfrom
feat/requirement-convergence

Conversation

@shinpr

@shinpr shinpr commented Jul 31, 2026

Copy link
Copy Markdown
Owner

Problem

implementation-approach Design Convergence already minimises the design surface for a requirement, but it treats the requirement itself as binding: a Failed Item is justified by "a current requirement" alone. That is the right contract for deciding how to build something, and it leaves what to build unexamined.

So a requirement that is bloated, internally ambiguous, or aimed at the wrong outcome gets minimised faithfully and built faithfully. Nothing upstream asks whether the requirement is worth its cost, and nothing carries the scope the user chose to exclude into design, planning, or review.

Approach

A new requirement-convergence skill holds the criteria and the hearing protocol. The three capabilities involved sit in different layers, so the skill is shared rather than owned:

  • the orchestrator can ask the user but cannot investigate
  • requirement-analyzer can investigate but cannot ask
  • the document owners can write but do not judge

This mirrors how external-resource-context already splits a hearing protocol, a storage location, and a downstream reference protocol across one skill.

What converges

Field Pass condition
outcome One observable result; a requirement that does not serve it is excess
requirements[] Each item labelled current-state, desired-future, or speculative
nonGoals[] Authored by the user, or the user stated there are none
cost A band with the structural evidence placing it, plus remaining unknowns

Flattening the three requirement layers into one list is what makes a bloated plan read as uniformly required, so the labels are what keep an idea raised in passing from becoming committed work.

cost is a rough band rather than an effort estimate. Requirements cannot support person-days, and its only consumer is a three-row challenge intensity table, so a low-cost reversible change is recorded and accepted while an irreversible one needs a user decision before design. Cost follows structure and count — call sites, boundaries crossed, existing equivalents, persisted-state conversion, verification support, unknowns — none of which requires reading what the code does.

Downstream

The record reaches design through the documents that already exist: outcome into the PRD's Success Criteria, non-goals and speculative items into Future / Out of Scope with an Origin column separating what the user authored from what the analysis judged, and a new Requirement Convergence section in the Design Doc for flows without a PRD. Fields the user agreed to leave unresolved stay visible in the Design Doc in every case.

Consumers treat non-goals and speculative requirements as excluded, and an unresolved field as an open question rather than a settled decision.

Scale

File count measures size, not structural impact, so a two-file change can still reshape a contract or a data flow. Structural Escalation raises the requirement to Medium at minimum when any ADR Creation Condition applies. It only raises a level; existing thresholds stand. No new criteria are introduced — the conditions were already documented, they simply did not reach the document gate.

Also in this branch

Prompt defects found while working through the above:

  • The hearing protocol's steps now name their completion evidence, so a skipped step is visible rather than silent
  • requirement-analyzer gains the Task Registration mandate every other agent carries
  • Prohibitions replaced with target states, including the training-cutoff note in four agents
  • The orchestrated recipes no longer register a rule-selection task, which had been pulling rule-advisor into flows that no flow table includes; its description now scopes it to work whose rules no defined process has determined

Compatibility

Additive. Existing artefacts stay valid, the new Design Doc section is skippable with a reason, and no template field changes meaning.

shinpr and others added 2 commits July 31, 2026 21:15
Design Convergence minimizes design surface for a given requirement, but
treats the requirement itself as binding — so a bloated, ambiguous, or
misdirected requirement is faithfully implemented at minimum surface.
Nothing upstream challenged the requirement, and nothing carried excluded
scope downstream.

Add a requirement-convergence skill holding the criteria and the hearing
technique. The orchestrator elicits (it owns AskUserQuestion), while
requirement-analyzer judges; both read the same skill. This mirrors the
external-resource-context split.

- Converge four fields: outcome, layered requirements, user-authored
  non-goals, and code-grounded cost, each with a readiness label
- Separate current-state / desired-future / speculative requirements so a
  bloated plan cannot read as uniformly required
- Scale challenge intensity by cost and reversibility, so cheap reversible
  requirements stay cheap to accept
- Persist the result to the PRD's Future / Out of Scope, or to the Design
  Doc's new Requirement Convergence section when no PRD exists
- Raise the document gate when a structural condition applies, so file
  count sets the floor rather than the whole rule

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The hearing protocol described the right behaviour in prose but gave each
step no completion evidence, so a step could be skipped without the skip
being visible. Non-goals in particular kept arriving as agent-authored
candidates the user only had to accept.

Restate the protocol as ordered steps that each name their evidence. The
step that records an answer requires the value to use wording the user
supplied, which keeps the user's judgement reviewable in the record rather
than depending on how the question was presented.

- Give requirement-analyzer the Task Registration mandate every other
  agent already carries, so its steps are serialised rather than optional
- Express readiness and date retrieval as target states with evidence
  instead of prohibitions
- Match the convergence JSON to the surrounding compression level
- Let each flow declare `cost` out of scope rather than offering a general
  escape from computing it
- Record `outcome` in the PRD's Success Criteria, matching where the PRD
  actually carries it, and name the non-goal origins `user` / `analysis`
- Keep Open questions in the Design Doc even when a PRD carries the rest
- Drop the convergence handoff to work-planner: a flow with no design
  document is a single hop from the hearing and needs no extra carrier

Adjacent prompt fixes found along the way:

- Stop the orchestrated recipes from registering a rule-selection task,
  which pulled rule-advisor into flows that no flow table includes
- Narrow rule-advisor's trigger to work whose rules no defined process has
  determined, so it stays a pre-work utility instead of a flow step
- Replace the training-cutoff prohibition with the `date` command already
  used elsewhere

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@shinpr shinpr self-assigned this Jul 31, 2026
shinpr and others added 2 commits August 1, 2026 00:37
WebSearch states the current month in its own tool description, so the
agents that judge information recency already receive the date at the point
they need it.

The step's distribution shows it was residue rather than a safeguard: one
agent ran it without holding WebSearch at all, four WebSearch-holding
agents never had it, and one half of the backend/frontend designer pair
carried it while the other did not. A safeguard tracks the capability that
needs it.

Removed from investigator, prd-creator, requirement-analyzer,
technical-designer, ui-spec-designer, and verifier.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Skills load through progressive disclosure, so a skill cannot know whether
another skill is present in context. Naming one asserts a dependency that
may not resolve. Composition belongs to the layers that know what is
loaded: a recipe, or an agent through its own frontmatter.

- requirement-convergence stated its boundary by naming two other skills;
  the boundary is now stated as sequencing, which needs no reference
- The Design Doc's Requirement Convergence section pointed at the skill
  that defines it; the section already carries its own semantics
- coding-principles pointed at another skill for heavier design decisions;
  it now names the decision types that warrant the fuller process

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@shinpr
shinpr merged commit 29b9210 into main Jul 31, 2026
1 check passed
@shinpr
shinpr deleted the feat/requirement-convergence branch July 31, 2026 15:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant